home *** CD-ROM | disk | FTP | other *** search
/ Windows Expert / Windows Expert.iso / windownt / caplib.zip / CAP.TXT < prev   
Text File  |  1992-10-30  |  11KB  |  444 lines
  1.  
  2.         Microsoft Windows NT Call Profiler README File
  3.  
  4.                 March 06, 1992
  5.                               September 22, 1992
  6.  
  7.  
  8.  
  9. 1.  Description:
  10. ----------------
  11.  
  12.     Windows NT (32-bit) Call/Attributive Profiler (CAP) for ix86 platform.
  13.  
  14.     CAP is a general purpose profiling tool that can be used to measure
  15.     the function call performance of .EXE's and .DLL's, (AKA modules),
  16.     in a variety of ways.  The following measurement methods are
  17.     supported:
  18.  
  19.         a)    Measuring calls from within an .EXE.
  20.  
  21.         b)    Measuring calls from within a .DLL.
  22.  
  23.         c)    Measuring calls from an .EXE to all of it's DLLs.
  24.  
  25.         d)    Measuring calls from one .DLL to all of its DLLs.
  26.  
  27.         e)    Measuring all the calls to specified .DLL's, from
  28.         any .EXE or .DLL.
  29.  
  30.         f)    Any arbitrary combination of a) through e).
  31.  
  32.     CAP creates a call tree of all the functions called in the EXE(s)/
  33.     DLL(s) being profiled.
  34.  
  35.  
  36.  
  37.  
  38. 2.  Profiling Files:
  39. --------------------
  40.  
  41.     o  cap.ini     -- Call Profiler initialization file.
  42.     o  cap.dll     -- Call Profiler DLL.
  43.     o  cap.lib     -- Profiler library file containing profiling entry
  44.                 points.
  45.     o  capdump.exe     -- Dump utility for dumping/clearing profiling
  46.                 data, and pausing profiling at any time.
  47.     o  capsetup.exe     -- Allows attaching/detaching cap.dll to/from all
  48.                 Windows applications.
  49.     o  readme     -- Call Profiler readme document (this file).
  50.  
  51.  
  52. 3.  Using the Call Profiler:
  53. ----------------------------
  54.  
  55.     o  Place CAP.INI in the root directory of C: drive and list all
  56.        the DLL/EXE images to be profiled as follows:
  57.  
  58.        [EXES]
  59.        Name of applications to be profiled. Each name should be on a
  60.        new line.
  61.  
  62.        [PATCH IMPORTS]
  63.        List of DLLs/EXEs to be patched for all of their imported entries.
  64.        Each name should be on a new line.
  65.  
  66.        [PATCH CALLERS]
  67.        List of DLLs to be profiled if called from the application or any of
  68.        its DLLs. Each name should be on a new line.
  69.  
  70.     o  Attach CAP.DLL to the application process. This can be done in two
  71.        ways:
  72.  
  73.        1)  Recompile your EXE/DLL using the "-Gp" and "-Zd" compiler
  74.            options.
  75.  
  76.            Link it with CAP.LIB using the "-debugtype:coff" and
  77.            "-debug:partial" linker options.
  78.  
  79.            This method will cause all the functions in the recompiled
  80.            sources to be profiled.
  81.  
  82.        2)  Run CapSetup.exe to attach CAP.DLL to all Windows applications.
  83.            Note that only those EXEs listed in the [EXES] section of
  84.            CAP.INI will be profiled.  Overhead for the non-profiled
  85.            applications is minimal.  See section 8, "Using CapSetup",
  86.            for CapSetup.exe usage.
  87.  
  88.  
  89.     o  Place CAP.DLL in your SYSTEM directory (i.e. ..\nt\system).
  90.  
  91.     o  Run the application.
  92.  
  93.     o  All the applications specified in the [EXES] section of the CAP.INI
  94.        will be profiled.
  95.  
  96.     o  Exit the application to dump the profiling data, or run CapDump.exe
  97.        to dump the data.  See section 6 "Profiling Data" for details.
  98.  
  99.  
  100.  
  101. 4.  Examples for Supported Measurment Methods:
  102. ----------------------------------------------
  103.  
  104.     Suppose we have .EXE's called ZOOMAN and HUNTED, and .DLLs called
  105.     ELEPHANT, MONKEY, SNAKE, WATER, and FOOD.  Let's assume the
  106.     following intercall dependencies exist:
  107.  
  108.     zooman.exe
  109.         - water.dll
  110.         - food.dll
  111.  
  112.     hunted.exe
  113.         - elephant.dll
  114.         -- water.dll
  115.         -- food.dll
  116.         - monkey.dll
  117.         -- water.dll
  118.         -- food.dll
  119.         - snake.dll
  120.  
  121.  
  122.  
  123.     a) Measuring calls from within ZOOMAN.EXE:
  124.  
  125.         o Recompile ZOOMAN and link it with CAP.LIB as described in
  126.           section 3.
  127.  
  128.         o Setup CAP.INI as follows:
  129.  
  130.           [EXES]
  131.           zooman.exe
  132.  
  133.           [PATCH IMPORTS]
  134.  
  135.           [PATCH CALLERS]
  136.  
  137.  
  138.  
  139.     b) Measuring calls from within WATER.DLL:
  140.  
  141.         o Recompile WATER and link it with CAP.LIB as described in
  142.           section 3.
  143.  
  144.         o Setup CAP.INI as follows:
  145.  
  146.           [EXES]
  147.           zooman.exe
  148.           hunted.exe
  149.  
  150.           [PATCH IMPORTS]
  151.  
  152.           [PATCH CALLERS]
  153.  
  154.         o Both ZOOMAN.EXE and HUNTED.EXE will be profiled for all the
  155.           calls within WATER.DLL.
  156.  
  157.  
  158.  
  159.      c) Measuring calls from HUNTED.EXE to it's DLLs:
  160.  
  161.         o Put "AppInit_DLLs=CAP.DLL" under [windows] section of WIN.INI
  162.           and reboot the system.
  163.  
  164.         o Setup CAP.INI as follows:
  165.  
  166.           [EXES]
  167.           hunted.exe
  168.  
  169.           [PATCH IMPORTS]
  170.           hunted.exe
  171.  
  172.           [PATCH CALLERS]
  173.  
  174.         o All calls from HUNTED.EXE to ELEPHANT.DLL, MONKEY.DLL,
  175.           and SNAKE.DLL will be profiled.
  176.  
  177.  
  178.  
  179.      d) Measuring calls from ELEPHANT.DLL and MONKEY.DLL to their DLLs:
  180.  
  181.         o Put "AppInit_DLLs=CAP.DLL" under [windows] section of WIN.INI
  182.           and reboot the system.
  183.  
  184.         o Setup CAP.INI as follows:
  185.  
  186.           [EXES]
  187.           hunted.exe
  188.  
  189.           [PATCH IMPORTS]
  190.           elephant.dll
  191.           monkey.dll
  192.  
  193.           [PATCH CALLERS]
  194.  
  195.         o All calls from ELEPHANT.DLL and MONKEY.DLL to WATER.DLL and
  196.           FOOD.DLL will be measured.
  197.  
  198.  
  199.  
  200.      e) Measuring all the calls to FOOD.DLL:
  201.  
  202.         o Put "AppInit_DLLs=CAP.DLL" under [windows] section of WIN.INI
  203.           and reboot the system.
  204.  
  205.         o Setup CAP.INI as follows:
  206.  
  207.           [EXES]
  208.           zooman.exe
  209.           hunted.exe
  210.  
  211.           [PATCH IMPORTS]
  212.  
  213.           [PATCH CALLERS]
  214.           food.dll
  215.  
  216.         o Both ZOOMAN.EXE and HUNTED.EXE will be profiled separately for
  217.           all the calls to FOOD.DLL.  For HUNTED.EXE all the calls from
  218.           both ELEPAHND.DLL and MONKEY.DLL to FOOD.DLL will be profiled.
  219.  
  220.  
  221.      f) Any arbitrary combination of a) through e):
  222.  
  223.         a+c) Measuring calls from within ZOOMAN.EXE and calls to it's DLLs:
  224.  
  225.         o Recompile ZOOMAN and link it with CAP.LIB as described in
  226.           section 3.
  227.  
  228.         o Setup CAP.INI as follows:
  229.  
  230.           [EXES]
  231.           zooman.exe
  232.  
  233.           [PATCH IMPORTS]
  234.           zooman.exe
  235.  
  236.           [PATCH CALLERS]
  237.  
  238.  
  239.         c+d) Measuring calls from HUNTED.EXE to it's DLLs and calls from
  240.          ELEPHANT and MONKEY DLLs to their DLLs:
  241.  
  242.         o Put "AppInit_DLLs=CAP.DLL" under [windows] section of WIN.INI
  243.           and reboot the system.
  244.  
  245.         o Setup CAP.INI as follows:
  246.  
  247.           [EXES]
  248.           hunted.exe
  249.  
  250.           [PATCH IMPORTS]
  251.           hunted.exe
  252.           elephant.dll
  253.           monkey.dll
  254.  
  255.           [PATCH CALLERS]
  256.  
  257.  
  258.  
  259.         a+c+d) Measuring calls from within HUNTED.EXE and calls to its DLLs
  260.            plus calls from ELEPHANT and MONKEY DLLs to their DLLs:
  261.  
  262.         o Recompile HUNTED and link it with CAP.LIB as described in
  263.           section 3.
  264.  
  265.         o Setup CAP.INI as follows:
  266.  
  267.           [EXES]
  268.           hunted.exe
  269.  
  270.           [PATCH IMPORTS]
  271.           hunted.exe
  272.           elephant.dll
  273.           monkey.dll
  274.  
  275.           [PATCH CALLERS]
  276.  
  277.  
  278.         b+d) Measuring calls from within ELEPHANT.DLL and calls to its DLLs:
  279.  
  280.         o Recompile ELEPHANT and link it with CAP.LIB as described in
  281.           section 3.
  282.  
  283.         o Setup CAP.INI as follows:
  284.  
  285.           [EXES]
  286.           hunted.exe
  287.  
  288.           [PATCH IMPORTS]
  289.           elephant.dll
  290.  
  291.           [PATCH CALLERS]
  292.  
  293.  
  294.  
  295.           * * * * * * * * * * * * *
  296.      * * *    R E S T R I C T I O N  * * *
  297.           * * * * * * * * * * * * *
  298.  
  299.      Do NOT measure calls within a DLL if the DLL's exported functions
  300.      are being measured from another EXE/DLL.  The following example shows
  301.      this incorrect combination which should be avoided:
  302.  
  303.         x) Measuring calls from ZOOMAN.EXE to its DLLs and calls within
  304.            WATER.DLL:
  305.  
  306.         o Recompile WATER and link it with CAP.LIB as described in
  307.           section 3.
  308.  
  309.         o Setup CAP.INI as follows:
  310.  
  311.           [EXES]
  312.           zooman.exe
  313.  
  314.           [PATCH IMPORTS]
  315.           zooman.exe
  316.  
  317.           [PATCH CALLERS]
  318.  
  319.         o Note that in addition to measuring calls within WATER.DLL, all
  320.           the calls from ZOOMAN.EXE to WATER.DLL are measured.  This is
  321.           not supported and will cause unexpected behavior.
  322.  
  323.  
  324.  
  325.  
  326. 5.  Exported Routines:
  327. ----------------------
  328.  
  329.     These exported entry points listed below can be used to control
  330.     profiling certain sections of code.  They can be combined with
  331.     any of the supported measurement methods mentioned above.
  332.  
  333.     o  StartCAP() : Clears profiling data & starts profiling
  334.     o  StopCAP()  : Stops profiling
  335.     o  DumpCAP()  : Dumps data for the current CAP.DLL instance
  336.  
  337.     A typical example (foo.exe):
  338.  
  339.         StartCAP();     // Clear exsiting profiling data and restart
  340.                 // profiling.
  341.         ..
  342.         ..            // application's code
  343.         ..
  344.  
  345.         StopCAP();        // Stop profiling without dumping data.
  346.         DumpCAP();        // Dump profiling data to FOO.CAP file.
  347.  
  348.  
  349.  
  350.  
  351. 6.  Profiling Data:
  352. -------------------
  353.  
  354.     o  Profiling data is captured in three ways:
  355.  
  356.        1)  Upon termination of the application profiling data is dumped
  357.            into a text file using the application name with .END
  358.            extension.
  359.  
  360.        2)  Using the dump utility, CapDump.exe, profiling data can be
  361.            dumped at any time.  Application name with .CAP extention will
  362.            be the data file name.  See section 7 "Using CapDump" for more
  363.            details.
  364.  
  365.        3)  Using exported routine DumpCAP().  Application name with .CAP
  366.            extention will be the data file name.
  367.  
  368.  
  369.     o  Data files are created in the same directory as the application
  370.        that is being profiled.
  371.  
  372.     o  Data is appended to data files every time a dump is performed.
  373.  
  374.     o  A separate call tree is generated for each thread in the process
  375.        context.  Different sections in the data file indicates data for
  376.        different threads in the process.
  377.  
  378.     o  The following data is dumped:
  379.  
  380.        - Call depth
  381.        - Function name
  382.        - Number of calls
  383.        - Total time for the function+callees
  384.        - Time per call for the function+callees
  385.        - Total time of the function only
  386.        - Time per call of the function only
  387.        - First time (function+callees)
  388.        - Minimum time (function+callees)
  389.        - Maximum time (function+callees)
  390.  
  391.  
  392.  
  393. 7.  Using CapDump:
  394. ------------------
  395.  
  396.     o  CapDump.exe can be used to pause profiling and clear/dump
  397.        profiling data for all the applications being profiled, at
  398.        any time.
  399.  
  400.     o  The following options are available via CapDump.exe:
  401.  
  402.           - Pause : Stops profiling (applications continue to run).
  403.  
  404.           - Clear and Restart : Clears any existing profiling data and
  405.                     restarts profiling.
  406.  
  407.           - Dump and Pause : Dumps any existing profiling data and stops
  408.                  profiling (applications continue to run).
  409.  
  410.     o  Data is dumped to a text file using the profiling applications name
  411.        with .CAP extension.    All fields are tab separated.    Data is
  412.        appended to data files with each dump.
  413.  
  414.     o  If calls are being profiled when data clearing is requested,
  415.        the time of clearing is used as the starting time for those
  416.        calls.
  417.  
  418.  
  419.  
  420. 8.  Using CapSetup:
  421. -------------------
  422.  
  423.     Usage:  CapSetup  -A | -D
  424.  
  425.       -A    Attaches CAP.dll to all Windows applications
  426.       -D    Detaches CAP.dll from all Windows applications
  427.  
  428.       Note:  System needs to be rebooted in order for the change to
  429.                  take effect.
  430.  
  431.  
  432.  
  433. 9.  Caveats:
  434. ------------
  435.  
  436.     o  Call profiler is an ix86 only DLL.
  437.  
  438.     o  If symbols are not available in an EXE/DLL that is being profiled,
  439.        ??? is displayed as the function name.
  440.  
  441.  
  442.  
  443. ** END OF README **
  444.